Pesquisa — Documentação oficial CRM&Bonus (EcomV2)

Data: 2026-05-15
Contexto: Task #193232 — Análise do fluxo de integração CRMBonus
Fontes:

Visão Geral da Integração

A API E-commerce v2 (EcomV2) permite que o cliente utilize seus bônus como forma de pagamento no momento da compra no site. O bônus é consumido diretamente do sistema CRM&Bonus — não é necessário criar cupons.

O fluxo é linear e sequencial: as chamadas ocorrem em ordem, pois há dependência de dados entre elas.

A API expõe dois conjuntos de endpoints com propósitos distintos:

Fluxo legado (baixa_bonus / finaliza_compra): resgate em duas etapas (reserva + efetivação).
Endpoint unificado (/bonus/execute): resgate e/ou geração de bônus em uma única chamada, com contrato diferente.

Ambientes

Ambiente	URL Base
Sandbox	`https://giftback-sandbox.crmbonus.com/apiEcommerce`
Produção	`https://www.crmbonus.com/apiEcommerce`

Autenticação — Headers obrigatórios

Todos os endpoints exigem os seguintes headers:

Header	Obrigatório	Descrição
`Authorization`	Sim	Token de autenticação (base64).
`CodEmpresa`	Sim*	Código da empresa fornecido pelo T.I. do CRM&Bônus (base64). *Opcional no `/finaliza_compra` e `/bonus/execute` conforme spec.
`Content-Type`	Sim	`application/json`
`System-Name`	Sim	Nome do sistema que realiza a requisição.
`User-Agent`	Sim	—

Operações da API

1. `baixa_bonus` — Reserva de bônus

Endpoint: POST {BaseURL}/baixa_bonus
Quando: No momento da criação do pedido, antes de qualquer processamento de pagamento.
Objetivo: Reserva o bônus do cliente, impedindo que o mesmo bônus seja utilizado em outros pedidos simultâneos.
Condição de disparo: Apenas quando bonus_resgatado > 0.

Requisição

{
    "loja_id": 100164,
    "user_id": 27056298,
    "valor_bruto": 500.50,
    "bonus_resgatado": 125.50,
    "ids_bonus": "136473650,136473651",
    "ticket": "CRM-TESTE-001"
}

Campo	Tipo	Obrigatório	Descrição
`loja_id`	int32	Sim	ID da loja na CRMBonus.
`user_id`	int32	Sim	ID do cliente na CRMBonus.
`valor_bruto`	float	Sim	Valor da compra antes da aplicação do saldo de bônus.
`bonus_resgatado`	float	Sim	Valor de bônus que será utilizado nessa compra.
`ticket`	string	Sim	Identificador da compra ou pedido no sistema.
`ids_bonus`	string	Não	IDs dos bônus sendo reservados (CSV).

Resposta

{
    "status": true,
    "data": {
        "title": "Sucesso!",
        "message": "Foi dada a baixa nos bônus utilizados."
    }
}

2. `finaliza_compra` — Efetivação do consumo

Endpoint: POST {BaseURL}/finaliza_compra
Quando: Após a captura bem-sucedida do pagamento.
Objetivo: Confirma o consumo do bônus que havia sido reservado na etapa anterior. Encerra o processo de bonificação do e-commerce.

Requisição

{
    "user_id": 27056298,
    "valor_bruto": 500.50,
    "bonus_resgatado": 125.50,
    "ids_bonus": "136473650,136473651",
    "ticket": "CRM-TESTE-001",
    "campanha_id": 20263,
    "items": [
        { "sku": "abc1234", "value_of": 100, "value_per": 100, "quantity": 1 }
    ],
    "payments": [
        { "id": "1", "system_id": "1", "system_name": "CASH", "type": "CASH", "value": 100, "installments": 1 }
    ],
    "delivery": { "type": "STANDARD", "fee": 5 },
    "totals": { "subtotal": 100, "fee": 0, "taxes": 0, "crm_discounts": 0, "other_discounts": 0, "total": 100 }
}

Campo	Tipo	Obrigatório	Descrição
`user_id`	int32	Sim	ID do cliente na CRMBonus.
`valor_bruto`	float	Sim	Valor da compra antes da aplicação do saldo de bônus.
`bonus_resgatado`	float	Sim	Valor do bônus resgatado nesta compra.
`ids_bonus`	string	Sim	IDs dos bônus disponíveis (retornados pelo `/consulta_bonus`).
`ticket`	string	Sim	Identificador da compra ou pedido no sistema.
`campanha_id`	string	Não	ID da campanha específica de geração.
`items`	array	Condicional*	Produtos da compra.
`payments`	array	Condicional*	Dados do pagamento.
`delivery`	array	Condicional*	Dados da entrega.
`totals`	array	Condicional*	Subtotal e descontos.

*Motor v2: Os campos items, payments, delivery e totals são obrigatórios apenas quando a configuração "motor v2" estiver ativa na CRMBonus.

Tipos de pagamento aceitos em payments.type:
CREDIT_CARD, DEBIT_CARD, CASH, PIX, BANK_SLIP, DIGITAL_WALLET, CHECK, FREIGHT_CARD, STORE_CARD, FOOD_VOUCHER, GIFT_CARD, FUEL_VOUCHER, BANK_DEPOSIT, BANK_TRANSFER, LOYALTY_PROGRAM, CASHBACK, STORE_CREDIT, INSTALLMENT_PLAN, UNSPECIFIED_ELECTRONIC_PAYMENT

Tipos de entrega aceitos em delivery.type:
PICKUP, STANDARD, EXPRESS, SCHEDULED

Resposta

{
    "status": true,
    "message": "sucesso",
    "data": {
        "bonus_id": 136473654,
        "order_id": 129898024,
        "ticket": "CRM-TESTE-001"
    }
}

Campo	Descrição
`bonus_id`	ID do bônus gerado a partir desta venda.
`order_id`	ID do pedido gerado na CRMBonus a partir desta venda.
`ticket`	Identificador da compra ou pedido no sistema.

3. `cancelarBonusEcom` — Cancelamento/liberação

Endpoint: POST {BaseURL}/cancelarBonusEcom
Quando: Em situações de cancelamento ou estorno do pedido.
Objetivo: Cancela o bônus associado ao pedido. O comportamento varia conforme o estado em que o bônus se encontra, sinalizado por used_bonus.

Requisição

{
    "num_pedido": "CRM-TESTE-001",
    "used_bonus": false
}

Campo	Tipo	Obrigatório	Descrição
`num_pedido`	string	Sim	Identificador do pedido — corresponde ao `ticket` enviado no `/baixa_bonus` ou `/finaliza_compra`.
`used_bonus`	boolean	Sim	Indica o estado do bônus no momento do cancelamento (ver tabela abaixo).

Semântica de `used_bonus` — atenção: contraintuitiva

A documentação oficial esclarece que used_bonus não indica se o bônus foi utilizado pelo cliente, mas sim qual operação precisa ser desfeita.

Valor	Significado	Quando usar
`true`	O bônus foi reservado via `/baixa_bonus` mas não efetivado — cancela apenas a reserva.	Pagamento recusado antes do `/finaliza_compra`.
`false`	O bônus foi gerado (após `/finaliza_compra`) mas ainda não usado pelo cliente — cancela o bônus gerado.	Pedido cancelado após confirmação do pagamento.

Resposta

{
    "status": true,
    "message": "Sucesso: Bonus cancelado com sucesso."
}

4. `bonus/execute` — Resgate e/ou geração unificados

Endpoint: POST {BaseURL}/bonus/execute
Quando: Alternativa ao fluxo baixa_bonus + finaliza_compra — executa resgate e/ou geração em uma única chamada.
Objetivo: Endpoint unificado para resgate de bônus existente (redeemed_bonus) e/ou geração de novo bônus (generated_bonus). Ao menos um dos dois deve estar presente na requisição.

Diferença de contrato: Este endpoint recebe os dados do cliente diretamente (não usa user_id numérico CRMBonus), usa internal_order_id em vez de ticket, e bonus_ids como array em vez de string CSV.

Requisição

{
    "user": {
        "phone": "11999864382",
        "name": "Ned Nix",
        "email": "ned.nix@crmbonus.com",
        "cpf": "07656553304"
    },
    "gross_value": 200,
    "generated_bonus": {
        "expiration_date_start": "2022-01-01T00:00:00",
        "expiration_date_end": "2022-01-01T00:00:00",
        "value": 50
    },
    "redeemed_bonus": {
        "bonus_ids": ["9873432", "2373134"],
        "value": 10
    },
    "internal_order_id": "60a3f6dc-01d4-4da5-81de-b43acb067504"
}

Campo	Tipo	Obrigatório	Descrição
`user`	object	Sim	Dados do cliente.
`user.phone`	string	Sim	Celular sem máscara (ex: `11999998888`).
`user.name`	string	Não	Nome do cliente.
`user.email`	string	Não	E-mail do cliente.
`user.cpf`	string	Não	CPF sem máscara.
`gross_value`	float	Sim	Valor da compra antes da aplicação do saldo de bônus.
`internal_order_id`	string	Sim	Identificador da compra ou pedido no sistema.
`generated_bonus`	object	Condicional†	Dados para geração de novo bônus.
`generated_bonus.expiration_date_start`	string	Não	Data inicial de validade (ISO 8601).
`generated_bonus.expiration_date_end`	string	Não	Data final de validade (ISO 8601).
`generated_bonus.value`	float	Não	Valor do bônus a ser gerado.
`redeemed_bonus`	object	Condicional†	Dados para resgate de bônus existente.
`redeemed_bonus.bonus_ids`	string[]	Não	IDs dos bônus sendo resgatados.
`redeemed_bonus.value`	float	Não	Valor dos bônus sendo resgatados.

† A requisição deve conter generated_bonus e/ou redeemed_bonus — ao menos um dos dois é obrigatório.

Resposta

{
    "status": true,
    "message": "Successfully generated bonus",
    "data": {
        "bonus_id": "6m6AU/VuGMZablszkpr8/w==",
        "order_id": "N1zy1v2v+p4BdT/TyHCRAg=="
    }
}

Fluxo Operacional (conforme documentação oficial)

Criação do pedido
    └── bonus_resgatado > 0?
        ├── SIM → baixa_bonus (reserva)
        │            └── Pagamento aprovado e capturado?
        │                ├── SIM → finaliza_compra (efetivação)
        │                └── NÃO → cancelarBonusEcom (used_bonus: true)
        └── NÃO → nenhuma ação CRM

Cancelamento após finaliza_compra
    └── cancelarBonusEcom (used_bonus: false)

Resumo: quando usar `used_bonus`

Cenário	`used_bonus`
Pagamento recusado (bônus só foi reservado, `/finaliza_compra` não foi chamado)	`true`
Pedido cancelado após confirmação (bônus efetivado via `/finaliza_compra`)	`false`

Observações relevantes

O fluxo é descrito como linear — as etapas não podem ser invertidas.
O parâmetro used_bonus tem semântica contraintuitiva: true indica cancelamento de reserva (pré-efetivação), false indica cancelamento de bônus gerado (pós-efetivação).
O endpoint /bonus/execute tem contrato distinto dos demais: recebe dados do cliente diretamente, usa internal_order_id em vez de ticket, e bonus_ids como array.
Campos items, payments, delivery e totals no /finaliza_compra são condicionais ao "motor v2" — não são obrigatórios no fluxo padrão.
A documentação oficial não cobre tratamento de erros — apenas o schema de resposta de sucesso (HTTP 200) está documentado.

Visão Geral da Integração​

Ambientes​

Autenticação — Headers obrigatórios​

Operações da API​

1. baixa_bonus — Reserva de bônus​

Requisição​

Resposta​

2. finaliza_compra — Efetivação do consumo​

Requisição​

Resposta​

3. cancelarBonusEcom — Cancelamento/liberação​

Requisição​

Semântica de used_bonus — atenção: contraintuitiva​

Resposta​

4. bonus/execute — Resgate e/ou geração unificados​

Requisição​

Resposta​

Fluxo Operacional (conforme documentação oficial)​

Resumo: quando usar used_bonus​

Observações relevantes​

Visão Geral da Integração

Ambientes

Autenticação — Headers obrigatórios

Operações da API

1. `baixa_bonus` — Reserva de bônus

Requisição

Resposta

2. `finaliza_compra` — Efetivação do consumo

Requisição

Resposta

3. `cancelarBonusEcom` — Cancelamento/liberação

Requisição

Semântica de `used_bonus` — atenção: contraintuitiva

Resposta

4. `bonus/execute` — Resgate e/ou geração unificados

Requisição

Resposta

Fluxo Operacional (conforme documentação oficial)

Resumo: quando usar `used_bonus`

Observações relevantes